PALLOCATE_COMMON_BUFFER_EX fonction de rappel (wdm.h)

Article
02/29/2024

La routine AllocateCommonBufferEx alloue de la mémoire pour une mémoire tampon commune et mappe cette mémoire afin qu’elle soit accessible à la fois par le processeur et par un appareil qui effectue des opérations DMA.

Syntaxe

PALLOCATE_COMMON_BUFFER_EX PallocateCommonBufferEx;

PVOID PallocateCommonBufferEx(
  [in]           PDMA_ADAPTER DmaAdapter,
  [in, optional] PPHYSICAL_ADDRESS MaximumAddress,
  [in]           ULONG Length,
  [out]          PPHYSICAL_ADDRESS LogicalAddress,
  [in]           BOOLEAN CacheEnabled,
  [in]           NODE_REQUIREMENT PreferredNode
)
{...}

Paramètres

[in] DmaAdapter

Pointeur vers une structure DMA_ADAPTER . Cette structure est l’objet adaptateur qui représente le périphérique DMA master bus ou le canal DMA système du pilote. L’appelant a obtenu ce pointeur à partir d’un appel précédent à la routine IoGetDmaAdapter .

[in, optional] MaximumAddress

Pointeur vers une variable qui contient l’adresse logique maximale pour la mémoire tampon commune. Ce paramètre indique que la mémoire tampon doit être allouée à partir de la mémoire sous cette adresse. Ce paramètre est facultatif et peut être spécifié comme NULL pour indiquer qu’il n’y a pas d’adresse maximale.

[in] Length

Taille, en octets, de la mémoire tampon commune qui doit être allouée à l’opération DMA.

[out] LogicalAddress

Pointeur vers une variable dans laquelle cette routine écrit l’adresse logique que l’appareil peut utiliser pour accéder à la mémoire tampon commune. L’appareil DMA doit utiliser cette adresse logique au lieu de l’adresse physique retournée par une routine telle que MmGetPhysicalAddress.

[in] CacheEnabled

Indique si la routine doit activer ou désactiver la mémoire mise en cache dans la mémoire tampon commune à allouer. Si la valeur est TRUE, la mise en cache est activée. Si la valeur est FALSE, elle est désactivée. Si la plateforme matérielle n’applique pas la cohérence du cache pour les opérations DMA, transmettez FALSE. Pour plus d’informations sur ce paramètre sur les processeurs ARM ou ARM 64 cibles, consultez Remarques.

[in] PreferredNode

Nœud NUMA préféré à partir duquel la mémoire doit être allouée. Si N est le nombre de nœuds NUMA dans un système multiprocesseur, PreferredNode est un nombre compris entre 0 et N–1. Pour un système monoprocesseur ou un système multiprocesseur non NUMA, définissez PreferredNode sur zéro.

Valeur retournée

AllocateCommonBufferEx retourne l’adresse virtuelle de la mémoire allouée pour la mémoire tampon commune. Si la mémoire tampon ne peut pas être allouée, null est retourné.

Remarques

AllocateCommonBufferEx n’est pas une routine système qui peut être appelée directement par nom. Cette routine peut être appelée uniquement par le pointeur de l’adresse retournée dans une structure DMA_OPERATIONS . Les pilotes obtiennent l’adresse de cette routine en appelant IoGetDmaAdapter avec le membre Version du paramètre DeviceDescription défini sur DEVICE_DESCRIPTION_VERSION3. Si IoGetDmaAdapter retourne NULL, la routine n’est pas disponible sur votre plateforme.

AllocateCommonBufferEx est une version étendue de la routine AllocateCommonBuffer . La liste suivante récapitule les fonctionnalités disponibles uniquement dans la version étendue :

L’appelant peut spécifier une adresse logique maximale pour la mémoire tampon commune à allouer.
L’appelant peut spécifier un nœud NUMA préféré dans lequel la mémoire tampon commune doit être allouée.

Sur les ordinateurs dotés de processeurs ARM ou ARM 64, les paramètres de cache dans l’ACPI système ont une priorité plus élevée que la valeur de paramètre CacheEnabled transmise par le pilote. Si la méthode _CCA ACPI indique que le cache de l’appareil n’est pas cohérent, le système d’exploitation désactive la mise en cache même si le pilote alloue de la mémoire mise en cache avec CacheEnabled défini sur TRUE.

Sur les ordinateurs dotés de processeurs ARM ou ARM 64, le système d’exploitation alloue une mémoire tampon commune non mise en cache en tant que mémoire de périphérique. Pour plus d’informations sur la mémoire tampon, consultez les sections A3.5.1 et A3.5.6 du Manuel de référence sur l’architecture ARMv7.

Le processeur n’autorise pas l’accès mal aligné à la mémoire de l’appareil. Votre pilote doit toujours accéder aux données de la mémoire tampon commune à l’aide d’opérations naturellement alignées. La plupart des routines du noyau n’acceptent pas la mémoire de périphérique comme paramètres d’entrée. Par exemple, un pilote réseau ne peut pas passer la mémoire du périphérique à NdisMIndicateReceiveNetBufferLists. Si votre pilote doit passer des données d’une mémoire tampon commune DMA à une routine de noyau, allouez la mémoire tampon avec CacheEnabled défini sur TRUE ou copiez les données de la mémoire tampon commune non mise en cache dans une allocation de pool temporaire.

Pour plus d’informations sur les opérations DMA qui utilisent une mémoire tampon commune, consultez les rubriques suivantes :

Utilisation de mémoires tampons communes

Utilisation de Common-Buffer Bus-Master DMA

Utilisation de Common-Buffer system DMA

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 8.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	PASSIVE_LEVEL