PALLOCATE_COMMON_BUFFER_EX fonction de rappel (wdm.h)
Le AllocateCommonBufferEx routine 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 d’adaptateur qui représente le périphérique DMA maître de bus du pilote ou le canal DMA système. 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 à allouer pour 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, passez LA valeur 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 à processeur unique ou un système multiprocesseur non NUMA, définissez PreferredNode sur zéro.
Valeur de retour
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, LA valeur NULL est retournée.
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 passée par le pilote. Si la méthode ACPI _CCA indique que 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 à partir du manuel de référence de 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 à partir de la mémoire tampon commune à l’aide d’opérations naturellement alignées. La plupart des routines de noyau n’acceptent pas la mémoire de l’appareil comme paramètres d’entrée. Par exemple, un pilote réseau ne peut pas passer la mémoire du périphérique dans NdisMIndicateReceiveNetBufferLists. Si votre pilote doit transmettre des données d’une mémoire tampon commune DMA à une routine de noyau, allouez la mémoire tampon avec CacheEnabled définie 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 :
utiliser des mémoires tampons courantes
utiliser Common-Buffer Bus-Master DMA
utiliser DMA système Common-Buffer
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Disponible à partir de Windows 8. |
| plateforme cible | Bureau |
| d’en-tête | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | PASSIVE_LEVEL |